/********************************************************************************

Two Wire Interface (TWI) utility functions.

Copyright (C) 2005 by Donald R. Blake
donblake at worldnet.att.net

This program is free software; you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

---------------------------------------------------------------------------------

Change Activity:

    Date       Description
   ------      -------------
  02 Sep 2005  Created.
  23 Oct 2005  Added twiStart, twiStop, twiWriteBytes and twiReadBytes.
               Include <compat/twi.h>.
  23 May 2006  Include <util/twi.h> instead of <compat/twi.h>.

********************************************************************************/



#ifndef _TWI_H_
#define _TWI_H_



/********************************************************************************

                                    Includes

********************************************************************************/

#include <stdint.h>
#include <stdbool.h>
#include <util/twi.h>



/*******************************************************************************

                                    twiInit

Iinitializes the TWI.  twiInit should be called before executing twiRead or
twiWrite.

*******************************************************************************/

void
twiInit(
  uint8_t timeout  // TWI timeout count (in time-out counter increments - see
                   // the twiDecTo function)
);



/********************************************************************************

                                    twiStart

twiStart generates a START condition and sends the SLA (Slave Address).

********************************************************************************/

uint8_t         // returns zero of no error; non-zero if error
twiStart(
  uint8_t sla,  // slave address (0..127)
  uint8_t rw    // read (TW_READ) or write (TW_WRITE)
);



/********************************************************************************

                                    twiStop

twiStop generates a STOP condition.

********************************************************************************/

uint8_t   // returns zero of no error; non-zero if error
twiStop(
  void
);



/*******************************************************************************

                                    twiWrite

twiWrite performs a complete TWI Master Transmit sequence.

*******************************************************************************/

uint8_t           // returns zero if no error; non-zero if error
twiWrite(
  uint8_t  sla,   // slave address (0..127)
  uint8_t* data,  // data byte(s) to write
  uint8_t  count  // number of bytes to write
);



/*******************************************************************************

                                    twiRead

twiRead performs a complete TWI Master Receive sequence.

*******************************************************************************/

uint8_t           // returns zero if no error; non-zero if error
twiRead(
  uint8_t  sla,   // slave address (0..127)
  uint8_t* data,  // data byte(s) read
  uint8_t  count  // number of bytes to read
);



/*******************************************************************************

                                 twiWriteBytes

twiWriteBytes writes one or more bytes.  twiWriteBytes does not generate a START
condition, transmit SLA (Slave Address) or generate a STOP condition.

*******************************************************************************/

uint8_t           // returns zero if no error; non-zero if error
twiWriteBytes(
  uint8_t* data,  // data byte(s) to write
  uint8_t  count  // number of bytes to write
);



/*******************************************************************************

                                  twiReadBytes

twiReadBytes reads one or more bytes.  twiReadBytes does not generate a START
condition, transmit SLA (Slave Address) or generate a STOP condition.

The read sequence can be performed one or more bytes at a time by multiple
calls to twiReadBytes.  All but the last call to twiReadBytes must use
nack == false.  The final call to twiReadBytes must use nack == true.

*******************************************************************************/

uint8_t            // returns zero if no error; non-zero if error
twiReadBytes(
  uint8_t* data,   // data byte(s) read
  uint8_t  count,  // number of bytes to read
  bool     nack    // if true, generate NACK on last byte read
);



/*******************************************************************************

                                    twiDecTo

Decrements the TWI time-out counter.  twiDecTo should be called at a fixed
periodic rate (see timeout parameter of the twiInit function).

*******************************************************************************/

void
twiDecTo(
  void
);



#endif // ifndef _TWI_H_
